fix(triggers,spec,service-automation)!: a time-triggered flow declares its acting organization and the run executes as it - #17334

Fixes #16659

Clause-②: yes — packages/spec/src/automation/index.ts gains re-export lines and the generated surface gains five rows: SCHEDULE_ORGANIZATION_KEY, ScheduleOrganizationSchema, the ScheduleOrganization type, resolveScheduleOrganization and describeMissingScheduleOrganization. New exported symbols on a published entry point. One more published symbol lands on a different package: @objectstack/lint re-exports FLOW_SCHEDULE_ORGANIZATION_MISSING. ⚠️ It was six until this round — findScheduleOrganizationNearMissInConfig is folded into the sentence that was its only consumer (A1 below), so the count above is the one that freezes.

⚠️ This pull request is a re-creation, and its branch is a re-push. The original (#17126, branch claude/issue-16659-schedule-trigger-acting-organization) was removed when the os-trump account was suspended. That PR is now unreachable (404) yet still holds its branch, so GitHub refuses a second PR on it — hence the -r2 name.

The first 14 commits are byte-identical to the original patched head b998f58f3832d3f8f952172bbd9b28f668f18ed9. ⛔ No rebase, no amend, no squash; this round is append-only on top of it.

⛔ What was lost and is NOT reconstructed here: the original PR body, and the CONTRACT_REVIEW_TIER review thread that returned the first head CHANGES REQUIRED. This PR has had no at-tier review at all as far as the record now shows, so it needs a fresh one rather than a re-review.

⭐ Round 3 (domain:spec seat) — the merge, the two must-fix items, and the advisories

Written from session session_01MkQhmuuJAVDjmeWNixwDDH; the contract review this round
discharges is comment 5619271717 on this PR, and the card's live Claim: is
5619338692. ⛔ Fenced to the merge and that review's findings — nothing about the design
is this round's to change, and F7 plus the near-miss vocabulary gap stay out.

1. The merge — per-path preservation, proved

mergeable_state was dirty. Merged (⛔ never rebased) through
scripts/pm/os-regen-merge.sh, with the risk list read from .gitattributes at merge
time: 18 routed patterns. Against merge base e669e5eee, 8 routed paths were moved
by this branch and 46 by main — and exactly one by both:
content/docs/references/index.mdx. That is the only path where the merge=os-regen
driver could drop a side, and it did: after the merge the file carried this branch's
schedule-organization row and had silently lost main's marketplace section, exit 0,
no conflict marker. Step 2 restored main's side; step 4 regenerated the whole chain on the
merged tree.

The proof, per routed path, each reading paired with a lit control (a path or marker
known to have moved, reading non-zero) and a dark control (a fabricated path or marker,
reading zero):

Both intents stack arithmetically in the regenerated index: 198 pages + 1 (this branch) − 11
(cloud retired on main) + 4 (marketplace arrived) = 192, which is what the file says.

Two non-generated conflicts were hand-resolved as semantic merges, both intents stacked:

• packages/spec/llms.txt — 205 + 1 − 11 + 4 = 199, and the merged table sums to 199.
• packages/spec/src/type-alias-convention.pin.test.ts — 811 − 30 + 1 + 1 = 783,
  recomputed from the merged file by the test's own predicate rather than from either
  side's arithmetic. ⚠️ The text merge also took both sides' NEW pin with no conflict
  marker, leaving two declarations sharing the id Iso871 (main's EnvironmentTypeSchema
  and this branch's ScheduleOrganizationSchema) — a duplicate-identifier error behind a
  merge that read clean. This branch's is renumbered Iso872; ids are claims about pins,
  not positions.

2. M1 — the ADR-0087 disposition was wrong on substance. Fixed.

not-required (no-migration-prescription) → registered schedule-flow-acting-organization-required, one new entry under
packages/spec/src/migrations/entries/semantic/, gen:migration-registry run. D3 covers
exactly this case, and the changeset's body is a prescription in D3's sense. Direct
precedent: rest-requireauth-default-flip (protocol 12) — behaviour-only, no shape moved,
a deployment judgement no transform can make, registered anyway.

⚠️ Registered under protocol 18, not 17 — the dispatch said 17 and the tree says
otherwise. registry.ts's step18 header states the convention in as many words:
"v17.0.0 was cut before these narrowings landed, so their migration prescriptions belong
to the NEXT major … The enforcement itself ships earlier on the 17.x line (launch-window
convention: accept-set narrowings ride minor releases); this step is where migrate meta
users are told, at the major boundary where they look." The same-shaped sibling
18.cloud-subpath-retired (#16325) is filed there too.

node scripts/check-adr-0087-registration.mjs --base origin/main, run post-commit
because the gate reads changesets from git: exit 0, and it names the entry as new
here — i.e. registered by this PR, not claimed against a pre-existing one.

⚠️ Worth one line for the next author: the adr-0087: registered marker's remainder is
parsed as a comma-separated id list, not as prose. Rationale that rides inside it reads
as several hundred nonexistent migration ids. The reasoning lives in the body instead.

3. M2 — the banner's single-organization sentence was false on driver-memory. Fixed, and it is NOT only a sentence.

Verified by running the driver's own exported predicate rather than a re-implementation
of it (assertCallNotTenantScoped, packages/drivers/driver-memory/src/memory-tenancy-guard.ts),
over all twelve doors it guards:

The guard has no organization-count limb at all: if (tenantId === undefined && tenantIds.length === 0) return;
and a throw otherwise. So a single-organization install is not exempt, and the banner's
"That install loses nothing at run time" was false there. The sentence is now
driver-conditional and names the refusal.

⛔ And the seat's question, answered: it is not only a sentence. On driver-memory a
time-triggered flow that touches genuinely per-organization data has no legal
configuration — declare an organization and every data node is refused per call; declare
none and the flow is not armed. The one configuration that is served, declaring the swept
objects platform-global (tenancy: { enabled: false }, ADR-0066), is the one the guard's
own message says must not be reached for on data that really is per-organization. That is a
functional gap on a supported driver wearing a documentation defect's clothes. ⛔ This round
does not fix it — it is out of the fence, and the remedy is a design decision (does a
time-triggered flow on a store with no tenant isolation get an explicit exemption, or is
driver-memory declared unsupported for time-triggered data flows?). Reported and stopped
at that boundary; the banner and the migration entry both now say the gap exists rather
than implying it does not.

4. A1 — one export folded. Five, not six.

findScheduleOrganizationNearMissInConfig is no longer published. Both callers
(validate-flow-trigger-readiness.ts, schedule-trigger.ts) ran it only to hand the answer
straight to describeMissingScheduleOrganization on the next line, so the scan moved inside
that function, which now takes describeMissingScheduleOrganization(flowName, { kind, config })
and consults the vocabulary itself. api-surface / export-origins / declaration-map and
the reference page regenerated; the symbol reads 0 across all four generated surfaces,
with describeMissingScheduleOrganization still present in two of them as the lit control.
⭐ A minor freezes what it publishes, and removing an export later is breaking where adding
one is not.

5. A2 — the name is KEPT, and the decision is a measurement, not a preference.

The question was whether time_relative is described as a "schedule" anywhere
authoritative. It is, in the place that governs authoring:

• FlowSchema.type is z.enum(['autolaunched', 'record_change', 'schedule', 'screen', 'api'])
  — there is no time_relative flow type. A time-relative sweep is authored as
  type: 'schedule'; the docs say so in as many words ("a schedule flow whose start
  node declares a timeRelative descriptor") and the renewalReminder example in
  content/docs/automation/flows.mdx literally sets type: 'schedule'.
• TimeRelativeTriggerSchema's own opening line: "A time_relative trigger sweeps an
  object on a schedule (daily by default)".
• resolveFlowTriggerKind's precedence note: a sweep "ALSO carries a schedule cadence
  (its sweep interval)", and it distinguishes a sweep from "a plain schedule flow" — a
  split inside the schedule family, not out of it.
• ADR text: zero mentions of time_relative / timeRelative across docs/adr/*.md
  (lit control: schedule matches many ADRs; dark control: a fabricated term matches none).
  The ADRs say nothing either way, so the enum and the docs are the authority.

⇒ Every flow this key applies to declares type: 'schedule'. ScheduleOrganization… is
accurate for both subjects and is kept; FlowActingOrganization… would have been a rename
away from the authorable vocabulary. Recorded in the module docblock so it is not
re-litigated after the freeze.

6. A4 / A5 / A6 — all three verified, all three now named

Each was checked against the tree before being written down, and each is in the banner
and in the migration entry's replacement:

• A4 — a NULL-organization row fans out N-fold. sql-driver.ts scopes with
  (field = :tenantId OR field IS NULL), and this PR's own negative-control fixture
  selects its organization_id: null row (c3) under scope — the asserted set is
  ['c1','c2','c3']. ⇒ after "one flow per organization", every such row is matched once
  per flow: N runs, N notifications, each acting as a different organization. Survives.
• A5 — the current window's dispatch claims are abandoned.
  scheduleDispatchKey returns `schedule:${flowName}:${window.startedAt}` and the
  sweep's key is `time-relative:${flowName}:${scope}:${id}`. Both embed the flow name,
  so N differently-named flows claim under N different keys. Survives.
• A6 — a run suspended before the upgrade is not retroactively confined.
  suspended-run-store.ts rehydrates with
  parseJson(row.context_json, {}); a row written before this change carries no tenantId,
  and nothing back-fills it. Survives (not a regression — it is how the run already ran —
  but the banner implied confinement without the carve-out).

7. Verification at head 18c0f6b44b

Gates. dispatch-gates derives 119 families for this change set; all 119 were run
with exit codes recorded and reconciled through --ran: 117 run / 2 NOT MEASURED / 0
UNRUN. The two are check:dual-build-cjs-loads and check:type-check-debt, both at
exit 3 — PREREQUISITE NOT MET (each reads a complete repo build). ⛔ Neither is a pass
and neither is a finding; both are hosted by CI, which builds first.
check:skill-examples refused the same way on the first attempt and was then genuinely
measured after building @objectstack/client-react: exit 0, 258 prose examples across 3
surfaces.

⚠️ origin/main moved again while this round ran, so dispatch-gates prints a STALE
TREE notice against the newest tip. The derivation above is against the tree at
18c0f6b44b; CI re-derives on the head it tests.

⛔ Still owed, and not this round's to take: the contract-review verdict must be re-taken
on the head that lands — this round moved it — and needs:contract-review stays on both
carriers until the seat clears it.

⚠️ Not backfilled, deliberately: the two remaining is being re-filed source comments
(examples/app-showcase/src/automation/flows/index.ts,
examples/app-todo/src/flows/task.flow.ts) still carry no number. The backfill was fenced
as opportunistic — only if you are touching those files anyway — and this round touches
neither. The changeset's copy of the sentence is updated to name #17396, because
the changeset was already being edited.

The ruling

Maintainer, 2026-09-08, verbatim: 「多组织定时任务本来只能在组织内运行，应该带组织ID，不允许跨组织的定时任务。」

⭐ This round: the ruling's other half

The first head declared the acting organization and put it on the RUN. The adversarial review on #16659 (comment 5615359989) found the complementary half missing, and the maintainer ruled option A — complete the ruling. The time_relative sweep was still selecting across every organization:

// before — time-relative-trigger.ts, the sweep's own query
await engine.find(desc.object, { where, limit: maxRecords, context: { isSystem: true } });

isSystem is authorization; tenantId is tenancy. Passing only the first made this a cross-organization scheduled task with a declaration papering over it: a sweep declared for org A matched rows in org B and launched one run per match, each stamped A. Downstream that is worse than the defect the card opened on:

• the run is scoped to A, so its update_record on a B row matches nothing — silently;
• notify posts into A's inbox about B's record — a cross-tenant disclosure that was previously refused outright, because an org-less run could write nowhere;
• the history row is stamped SUBJECT-first, so it lands under B while the inbox rows sit under A. One run, three organizations' opinions about whose it was.

The fix, and why this mechanism and not a predicate

The declared organization now rides the sweep's own query as context.tenantId — the same ExecutionContext axis the run already uses. Engine.buildDriverOptions turns it into DriverOptions.tenantId and the driver scopes the read. Both members are keys EngineQueryOptions.context already accepts (ExecutionContextSchema.partial()), so naming tenantId on the trigger's structural data-engine slice widens no contract; it declares the slice it uses.

⛔ Not a hand-built organization_id predicate on where. That would be a second implementation of tenancy inside a trigger: it would hardcode a column the object is free to rename (tenancy.tenantField), select nothing on a platform-global object that has no such column, break a federated object outright, and — worst — read as a scoped query to a driver that never learned the caller wanted scoping, so a driver with no isolation would answer it silently instead of refusing it.

Both new silences are closed, because that failure mode is this card's own subject

• A store that cannot honour the scope refuses the call. driver-memory implements no row-level tenant isolation and refuses anything handed a tenant scope (MEMORY_MULTI_TENANT_UNSUPPORTED, [finding] The InMemory driver silently ignores the engine's tenant scope for objects that OMIT a tenancy block — its guard only refuses an explicit enabled: true, so memory-driver runs show cross-organization rows a SQL driver refuses #16589). The sweep's failure is now logged at error rather than warn — stderr survives the CLI's boot-quiet window, and "this sweep can no longer see anything" became a reachable state the moment the query was scoped.
• On a tenancy.enabled: false (ADR-0066) or federated (ADR-0015) object the engine drops the scope, so the declaration cannot narrow that sweep at all — it still selects across every organization while its runs act as the declared one. The trigger says so at bind, at warn, naming the object. ⛔ It does not pretend the flow is contained. That branch is a disclosure only: it never changes which rows come back, so a drift from the engine's predicate costs a wrong warning, never a wrong row.
• The bind line now names the acting organization, so a sweep's reach is readable from the boot log.

The rest of the review's blocking findings

• F1 / F3 — the changeset said something false, twice. It claimed "Nothing that was already delivering stops delivering" and, three paragraphs later, that on a single-organization install such a flow "was working" (system-write-organization.ts:268-273 confirms the second). The banner now states the narrowing in two places — the bind-time accept set AND the run-time data plane, which no sentence in it previously mentioned — and carries the migration consequence an operator reads release notes for: a deployment running ONE time-triggered flow across ALL organizations must now declare one flow per organization.
• F4 — authoring learns the rule. validate-flow-trigger-readiness.ts held zero occurrences of organization, against engine.ts:21-27's own invariant. It now carries flow-schedule-organization-missing, re-implementing no judgement: resolveFlowTriggerKind says which flows owe the key, resolveScheduleOrganization says whether one was declared, describeMissingScheduleOrganization writes the sentence. Severity warning, measured not argued — see below.
• F5 — the shipped examples. All four package-shipped time-triggered flows stop firing and now say so where an author meets them.
• F8 — a comment this change made false (suspended-run-store.ts: "a plain scheduled sweep has neither and keeps NULL") now says what happens, keeping the SUBJECT-first precedence it documents.
• F9 — sync and regenerate. Merged origin/main through scripts/pm/os-regen-merge.sh (⛔ no rebase). The one content conflict, type-alias-convention.pin.test.ts, was a semantic merge of two stacking intents — main's −4 (ui#6206-B, 815 → 811) and this branch's +1 (Iso871) — resolved to 812, recomputed from the file rather than by arithmetic, with both narratives kept. Generated artifacts were then regenerated wholesale on the merged tree: totals 198/1583 → 199/1584, automation 13/73 → 14/74.

⛔ F7 was left alone, and so was the whole bind-time half: the review found it well built and genuinely pinned, and this round does not touch it. F6 is the PM's.

The severity decision was measured, not asserted

On the never-fire family's own criterion (#5762 — is this stack enough to know the flow is dead?) the new lint id belongs at error. It is held at warning because of the corpus, and that was run rather than reasoned: with the severity flipped to error, objectstack build on examples/app-showcase fails, naming showcase_task_due_reminder and showcase_scheduled_digest. Neither can be repaired by authoring — the only legal value is a sys_organization.id minted per install at runtime, and ⛔ a placeholder id is strictly worse than the omission. Promoting the id is a consequence of the open maintainer decision about package-shipped time-triggered flows, not a lint choice. The probe was restored byte-identically (blob == pre-probe blob) and both example builds pass at warning, flagging exactly the four shipped flows.

⚠️ The card that carried that decision — #17150 — is 404, destroyed with the suspended account, and is being re-filed by the PM. This PR does not invent a number for it: the four in-source comments and the changeset carry the record instead, and the number is owed once the new card exists (grep is being re-filed).

Verification

The differential control

⛔ A test that only proves "A's rows are found" does not distinguish the fix from the defect — the defect found them too, alongside B's. So the discriminating number is the count of launched runs.

packages/qa/dogfood/test/schedule-sweep-organization-scope.dogfood.test.ts boots the real automation + messaging + ObjectQL stack with two organizations, one matching row in A and two in B, and a time_relative flow declared for A. On sqlite-wasm: exactly 1 run launches (3 is the unfixed reading), update_record lands on A's row and no other, and no sys_notification names a B record. On memory: the scoped sweep is refused and reported at error, with a paired control proving the refusal is about the scope and not about the fixture.

Negative control — measured, not argued

Two legs over one fixture: the sweep as it ships (scoped) and the same query with isSystem only, which is the pre-fix sweep byte for byte. Asserted equal. The fixture carries a NULL-organization row on purpose — the driver's scope is org = :tenant OR org IS NULL, so a platform row stays visible to a scoped read, and that is part of "identical" rather than an exception to it. Non-vacuous in both directions: the selected set is asserted to be the three rows, and leg A is asserted to have really asked for a scope, so this pin reddens under the same ablation as the differential instead of being one that can never fail. Its opposite limb is the DIFFERENTIAL above: add a second organization and the two legs must diverge.

What a single-organization install does feel is the bind-time half — the flow is unarmed until it declares one line — and the changeset now says so instead of denying it.

Ablation — direction predicted in writing first, then measured

Reverting the sweep's context to the pre-fix bytes, in one shell under trap … EXIT INT TERM, with the mutation proven on disk before either run (fixed spelling 1 → 0, ablated spelling 0 → 1, git diff --numstat = 1/1):

As predicted, the run acts on the DECLARED organization's record stayed green under ablation — the run is scoped either way — which is exactly why the run count, not the write, carries the proof. One unit failure beyond the three enumerated: the unit twin of the memory-refusal pin, predicted for dogfood and omitted from the unit list.

Restoration proven by state, not by exit code: git diff HEAD empty, git hash-object == the HEAD blob, git status --porcelain clean. Both suites resolve @objectstack/trigger-schedule to source (dogfood's vitest alias + tsconfig paths; the pair is absent from KNOWN_UNALIASED_TEST_IMPORTS), so no dist/ could retain the mutation.

Full suites at the round-2 head 5fb332bdc (superseded — see Round 3 §7 for head 18c0f6b44b)

⛔ Reported as NEW numbers, not as confirmations: nothing on this branch had been run against that day's main at all.

Gates. dispatch-gates derived 117 families for this change set; all 117 were run with exit codes recorded and reconciled via --ran: 116 run / 1 NOT-MEASURED / 0 UNRUN. The one is check:dual-build-cjs-loads at exit 3 — PREREQUISITE NOT MET (it reads a complete pnpm build); ⛔ that is not a pass. It is hosted by ci.yml's build-core job, and Build Core is green on this head, so the gate is measured — by CI, not locally. Chasing it locally package-by-package produced a different finding set on every run against a partial tree, naming only packages this diff never touches: a fact about build state, never about the diff.

Scope

Against today's origin/main (merge base e669e5eee): 42 files, +3045 / −53. The patch round itself is 15 files, +1273 / −65 on top of the original head — trigger-schedule's sweep and its pins, the dogfood differential control and its fixture, the lint rule and its suite, the changeset, the flows guide, the four example-flow comments, and one stale comment in suspended-run-store.

⛔ Out of scope and untouched: the bind-time refusal, its pins, and the six spec exports the original head added.

Generated by Claude Code